home *** CD-ROM | disk | FTP | other *** search
TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) NNNNAAAAMMMMEEEE tserialio, libtserialio, tsintro, tsClosePort, tsCopyConfig, tsFreeConfig, tsGetErrorHandler, tsGetFD, tsGetFillPoint, tsGetFillPointBytes, tsGetFilledBytes, tsNewConfig, tsNewConfigFromPort, tsOpenPort, tsRead, tsSetCflag, tsSetDirection, tsSetErrorHandler, tsSetExternalClockFactor, tsSetFillPointBytes, tsSetOspeed, tsSetPortName, tsSetProtocol, tsSetQueueSize, tsWrite - timestamped serial port i/o CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ttttsssseeeerrrriiiiaaaalllliiiioooo....hhhh>>>> Link with -ltserialio Choosing a Port Configuration: TTTTSSSSccccoooonnnnffffiiiigggg ttttssssNNNNeeeewwwwCCCCoooonnnnffffiiiigggg((((vvvvooooiiiidddd))));;;; TTTTSSSSccccoooonnnnffffiiiigggg ttttssssNNNNeeeewwwwCCCCoooonnnnffffiiiiggggFFFFrrrroooommmmPPPPoooorrrrtttt((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; TTTTSSSSccccoooonnnnffffiiiigggg ttttssssCCCCooooppppyyyyCCCCoooonnnnffffiiiigggg((((TTTTSSSSccccoooonnnnffffiiiigggg ffffrrrroooommmm))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssFFFFrrrreeeeeeeeCCCCoooonnnnffffiiiigggg((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttPPPPoooorrrrttttNNNNaaaammmmeeee((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttDDDDiiiirrrreeeeccccttttiiiioooonnnn((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt ddddiiiirrrreeeeccccttttiiiioooonnnn))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttQQQQuuuueeeeuuuueeeeSSSSiiiizzzzeeee((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt qqqquuuueeeeuuuueeeessssiiiizzzzeeee))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttCCCCffffllllaaaagggg((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, ttttccccffffllllaaaagggg____tttt ccccffffllllaaaagggg))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttOOOOssssppppeeeeeeeedddd((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, ssssppppeeeeeeeedddd____tttt oooossssppppeeeeeeeedddd))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttPPPPrrrroooottttooooccccoooollll((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt pppprrrroooottttooooccccoooollll))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttEEEExxxxtttteeeerrrrnnnnaaaallllCCCClllloooocccckkkkFFFFaaaaccccttttoooorrrr((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt eeeexxxxttttcccclllloooocccckkkk____ffffaaaaccccttttoooorrrr))));;;; Opening and Using a Port: TTTTSSSSssssttttaaaattttuuuussss ttttssssOOOOppppeeeennnnPPPPoooorrrrtttt((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, TTTTSSSSppppoooorrrrtttt ****rrrreeeettttuuuurrrrnnnnPPPPoooorrrrtttt))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssCCCClllloooosssseeeePPPPoooorrrrtttt((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; iiiinnnntttt ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssRRRReeeeaaaadddd((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****ddddaaaattttaaaa,,,, ssssttttaaaammmmpppp____tttt ****ssssttttaaaammmmppppssss,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssWWWWrrrriiiitttteeee((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****ddddaaaattttaaaa,,,, ssssttttaaaammmmpppp____tttt ****ssssttttaaaammmmppppssss,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; iiiinnnntttt ttttssssGGGGeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; iiiinnnntttt ttttssssGGGGeeeettttFFFFDDDD((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; Error Handling: TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc ttttssssSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc nnnneeeewwwwffffuuuunnnncccc,,,, iiiinnnntttt iiiinnnncccclllluuuuddddeeeeffffuuuunnnnccccnnnnaaaammmmeeee))));;;; TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc ttttssssGGGGeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((iiiinnnntttt ****iiiinnnncccclllluuuuddddeeeeffffuuuunnnnccccnnnnaaaammmmeeee))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The tserialio library provides millisecond accurate, timestamped access to a serial port. An application can measure the time at which each input byte arrived at a serial port to within plus or minus one millisecond. An application can also schedule bytes to go out a serial PPPPaaaaggggeeee 1111 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) port at a specified time in the future. The operating system will output each byte at the specified time with an accuracy of plus or minus one millisecond. Times are specified on the UST timeline, the same timeline used for other devices such as audio and video (see ddddmmmmGGGGeeeettttUUUUSSSSTTTT(3dm)). See ACCURACY AND LATENCY below for more information about the accuracy and latency guarantees which tserialio offers. Tserialio is useful for timely serial port tasks such as machine control, video deck control, or motion capture. It is also useful for MIDI, though the MIDI library (see mmmmddddIIIInnnnttttrrrroooo(3dm)) may be more appropriate in this case. Tserialio is currently only supported on O2 workstations. OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW A TSport represents one serial port open in one direction. In order to open a TSport, you specify how you would like the port configured using a TSconfig. This code shows you how to create a TSconfig and set its various members: { TSconfig config = tsNewConfig(); TSport port; tsSetPortName(config, "/dev/ttyts1"); /* required */ tsSetDirection(config, TS_DIRECTION_TRANSMIT); /* required */ tsSetQueueSize(config, 200); /* required */ tsSetCflag(config, CS8|PARENB|PARODD); /* required */ tsSetOspeed(config, 38400); /* required */ tsSetProtocol(config, TS_PROTOCOL_RS232); /* optional */ tsSetExternalClockFactor(config, 0); /* optional */ if (TS_SUCCESS != tsOpenPort(config, &port)) exit(2); tsFreeConfig(config); ... use the port ... tsClosePort(port); } The C types TSport and TSconfig are opaque pointers which you should simply pass into the tserialio calls and never dereference. The format of the data to which they point is not exported. If you opened a TS_DIRECTION_TRANSMIT port, then use code like this to actually schedule bytes for output: PPPPaaaaggggeeee 2222 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) { stamp_t stamps[NBYTES]; unsigned char data[NBYTES]; int i; for(i=0; i < NBYTES; i++) { data[i] = a byte of data; stamps[i] = UST time to transmit that byte; } tsWrite(port, &data, &stamps, NBYTES); } If you opened a TS_DIRECTION_RECEIVE port, then use code like this to acquire input bytes and their arrival times: { stamp_t stamps[NBYTES]; unsigned char data[NBYTES]; tsRead(port, &data, &stamps, NBYTES); int i; for(i=0; i < NBYTES; i++) { data[i] contains a byte of data; stamps[i] contains UST time at which byte arrived; } } A TSport has a queue of (byte,timestamp) pairs whose capacity you specify with ttttssssSSSSeeeettttQQQQuuuueeeeuuuueeeeSSSSiiiizzzzeeee(3). For an input port (TS_DIRECTION_RECEIVE), this queue holds the bytes which have been received but which you have not yet read using ttttssssRRRReeeeaaaadddd(3). Characters that arrive on a port whose queue is full will be discarded. If you attempt to read more characters than are currently available on the queue, then ttttssssRRRReeeeaaaadddd(3) will block until your request can be satisfied. For an output port (TS_DIRECTION_TRANSMIT), this queue holds the bytes which you have enqueued using ttttssssWWWWrrrriiiitttteeee(3) but which have not yet been transmitted. If you attempt to enqueue so much data that this queue would fill past its capacity, then ttttssssWWWWrrrriiiitttteeee(3) will block until enough space has become available to enqueue all of your data. You can determine the number of (byte,timestamp) pairs currently enqueued on a TSport using ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss(3). You can also use ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss(3) and ttttssssGGGGeeeettttFFFFDDDD(3) to get a file descriptor for use in sssseeeelllleeeecccctttt(2) or ppppoooollllllll(2) which will unblock when a specified amount of data or space has become available in a TSport. TS functions which can err return a TSstatus. A return value of TS_SUCCESS means that the function was successful, otherwise a TS_ERROR_ token is returned to describe the error. See ERROR HANDLING below for PPPPaaaaggggeeee 3333 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) more information. CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRIIIINNNNGGGG AAAA PPPPOOOORRRRTTTT TTTTSSSSccccoooonnnnffffiiiigggg ttttssssNNNNeeeewwwwCCCCoooonnnnffffiiiigggg((((vvvvooooiiiidddd))));;;; Create a new TSconfig. Can fail with NULL (oserror()==TS_ERROR_OUT_OF_MEM). TTTTSSSSccccoooonnnnffffiiiigggg ttttssssNNNNeeeewwwwCCCCoooonnnnffffiiiiggggFFFFrrrroooommmmPPPPoooorrrrtttt((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; Create a new TSconfig with the same configuration as _p_o_r_t. Can fail with NULL (oserror()==TS_ERROR_OUT_OF_MEM). TTTTSSSSccccoooonnnnffffiiiigggg ttttssssCCCCooooppppyyyyCCCCoooonnnnffffiiiigggg((((TTTTSSSSccccoooonnnnffffiiiigggg ffffrrrroooommmm))));;;; Create a new TSconfig in exactly the same state as _f_r_o_m. _F_r_o_m is not modified. Can fail with NULL (oserror()==TS_ERROR_OUT_OF_MEM). TTTTSSSSssssttttaaaattttuuuussss ttttssssFFFFrrrreeeeeeeeCCCCoooonnnnffffiiiigggg((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg))));;;; Free a TSconfig. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttPPPPoooorrrrttttNNNNaaaammmmeeee((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;; Set UNIX filename of timestamped serial port to open. This should be a UNIX device node of the form ////ddddeeeevvvv////ttttttttyyyyttttssssn. ////ddddeeeevvvv////ttttttttyyyyttttssssn represents the same physical port as the traditional device node ////ddddeeeevvvv////ttttttttyyyyddddn as described in sssseeeerrrriiiiaaaallll(7). This call can fail with TS_ERROR_OUT_OF_MEM. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttDDDDiiiirrrreeeeccccttttiiiioooonnnn((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt ddddiiiirrrreeeeccccttttiiiioooonnnn))));;;; Specify direction of timestamped serial port: o TS_DIRECTION_TRANSMIT for an "output" port to which you can ttttssssWWWWrrrriiiitttteeee(3). o TS_DIRECTION_RECEIVE for in "input" port from which you can ttttssssRRRReeeeaaaadddd(3). o call fails with TS_ERROR_BAD_LIBRARY_CALL for any other _d_i_r_e_c_t_i_o_n TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttQQQQuuuueeeeuuuueeeeSSSSiiiizzzzeeee((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt qqqquuuueeeeuuuueeeessssiiiizzzzeeee))));;;; Specify the number of (byte,timestamp) pairs which the port's queue can hold. Fails with TS_ERROR_BAD_LIBRARY_CALL if specified size is 0 or less. Currently, the queue size must be greater than or equal to 20, and less than 102400. See OVERVIEW above for information about this queue. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttCCCCffffllllaaaagggg((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, ttttccccffffllllaaaagggg____tttt ccccffffllllaaaagggg))));;;; Specify most serial communication parameters, using the traditional struct termios.c_cflag flags (see tttteeeerrrrmmmmiiiioooossss(7)): PPPPaaaaggggeeee 4444 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) CSIZE bits (CS5, CS6, CS7, CS8) CSTOPB bit (1==2 stop bits, 0==1 stop bits) PARENB (0==no parity, 1==see PARODD) PARODD (1==odd parity, 0==even parity) CBAUD (B9600 etc.) is IGNORED this field of c_cflag has been obsoleted. use tsSetOspeed(3) instead. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttOOOOssssppppeeeeeeeedddd((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, ssssppppeeeeeeeedddd____tttt oooossssppppeeeeeeeedddd))));;;; Specify baud rate as integer in symbols per second (e.g. 9600, 31250 (MIDI), 38400 (video deck control)). Fails with TS_ERROR_BAD_LIBRARY_CALL if _s_p_e_e_d is 0. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttPPPPrrrroooottttooooccccoooollll((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt pppprrrroooottttooooccccoooollll))));;;; Specify electrical protocol to use on serial port: o TS_PROTOCOL_RS232 (the default): EIA/TIA-232-E o TS_PROTOCOL_RS422: EIA/TIA-422-B o TS_PROTOCOL_MACINTOSH: Macintosh compatible serial levels o fails with TS_ERROR_BAD_LIBRARY_CALL for other _p_r_o_t_o_c_o_l. See sssseeeerrrriiiiaaaallll(7) for information about which protocols are supported on which platforms. TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttEEEExxxxtttteeeerrrrnnnnaaaallllCCCClllloooocccckkkkFFFFaaaaccccttttoooorrrr((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, iiiinnnntttt eeeexxxxttttcccclllloooocccckkkk____ffffaaaaccccttttoooorrrr))));;;; Specify clock source for serial port: o 0 (the default) means the serial port should use its internal clock. o N (N > 1) means the serial port should clock itself off of the provided external clock divided by N. ttttssssSSSSeeeettttOOOOSSSSppppeeeeeeeedddd(3) is ignored in this case. o N < 0 fails with TS_ERROR_BAD_LIBRARY_CALL. To use a Macintosh-compatible MIDI dongle plugged into a serial port of an Indigo, Indy, and Indigo2, specify 32. The MIDI dongle provides a 1 MHz external clock signal on a pin of the serial port, which drives the serial port at the MIDI (1,000,000/32==31.25kHz) baud rate. On the O2 system, use the internal clock and set ospeed to 31250. OOOOPPPPEEEENNNNIIIINNNNGGGG AAAANNNNDDDD UUUUSSSSIIIINNNNGGGG AAAA PPPPOOOORRRRTTTT TTTTSSSSssssttttaaaattttuuuussss ttttssssOOOOppppeeeennnnPPPPoooorrrrtttt((((TTTTSSSSccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg,,,, TTTTSSSSppppoooorrrrtttt ****rrrreeeettttuuuurrrrnnnnPPPPoooorrrrtttt))));;;; PPPPaaaaggggeeee 5555 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) Open a timestamped serial port. Each TSport represents a connection to one physical serial port in one direction. Each TS_DIRECTION_RECEIVE TSport will receive its own copy of the data arriving at the physical serial port. On TS_PROTOCOL_RS232 serial ports, DTR and RTS are always asserted, and DCD and CTS are ignored. Hanging up the serial line (see tttteeeerrrrmmmmiiiioooossss(3)) is not currently supported. ttttssssOOOOppppeeeennnnPPPPoooorrrrtttt(3) can fail in the following cases: o TS_ERROR_BAD_LIBRARY_CALL if _c_o_n_f_i_g or _r_e_t_u_r_n_P_o_r_t are NULL or invalid. o TS_ERROR_BAD_LIBRARY_CALL if you had not set the following parameters of _c_o_n_f_i_g: ttttssssSSSSeeeettttPPPPoooorrrrttttNNNNaaaammmmeeee(3), ttttssssSSSSeeeettttDDDDiiiirrrreeeeccccttttiiiioooonnnn(3), ttttssssSSSSeeeettttQQQQuuuueeeeuuuueeeeSSSSiiiizzzzeeee(3), ttttssssSSSSeeeettttCCCCffffllllaaaagggg(3), or ttttssssSSSSeeeettttOOOOssssppppeeeeeeeedddd(3). o TS_ERROR_OPENING_PORT if a parameter specified in _c_o_n_f_i_g is not supported on the specified serial port, or there is some problem interfacing with the tserialio driver. o TS_ERROR_OPENING_PORT if _c_o_n_f_i_g specifies an invalid queuesize (see ttttssssSSSSeeeettttQQQQuuuueeeeuuuueeeeSSSSiiiizzzzeeee(3)). o TS_ERROR_OPENING_PORT if opening the port would exceed tserialio's fixed per-system limit on the number of simultaneously open TSports. This limit is at least eight times the number of physical serial ports on the machine. o TS_ERROR_PORT_BUSY if _c_o_n_f_i_g specifies TS_DIRECTION_TRANSMIT on a port which is already open for transmit using tserialio. o TS_ERROR_PORT_BUSY if _c_o_n_f_i_g specifies a physical port which is already open using tserialio with different communications parameters (cflag, ospeed, protocol, or extclock). o TS_ERROR_PORT_BUSY if _c_o_n_f_i_g specifies a port which is already open using the traditional serial interface (see sssseeeerrrriiiiaaaallll(7)). o TS_ERROR_OUT_OF_MEM. TTTTSSSSssssttttaaaattttuuuussss ttttssssCCCClllloooosssseeeePPPPoooorrrrtttt((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; Close a TSport. If the port is a TS_DIRECTION_TRANSMIT port, all currently enqueued (byte,timestamp) pairs will be discarded immediately and not transmitted. iiiinnnntttt ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; Returns the total number of (byte,timestamp) pairs currently in the TSport's queue. PPPPaaaaggggeeee 6666 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSssssttttaaaattttuuuussss ttttssssRRRReeeeaaaadddd((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****ddddaaaattttaaaa,,,, ssssttttaaaammmmpppp____tttt ****ssssttttaaaammmmppppssss,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; Reads nbytes (byte,timestamp) pairs from the specified port's queue. The port must be a TS_DIRECTION_RECEIVE port (see ttttssssSSSSeeeettttDDDDiiiirrrreeeeccccttttiiiioooonnnn(3)). The function returns the data of each byte in data[i], and the UST time at which the byte came in the input jack of the machine in stamps[i]. The actual reception time of data[i] is guaranteed to be within the interval from (stamps[i] - 2 milliseconds) to (stamps[i]). If nbytes (byte,timestamp) pairs are not currently available in the port's queue, then ttttssssRRRReeeeaaaadddd(3) will block until it has been able to read all nbytes pairs. If ttttssssRRRReeeeaaaadddd(3) needs to block, it will call sssseeeelllleeeecccctttt(2). If that select fails for any reason other than EINTR, the call will return with TS_ERROR_SELECT_FAILED. Currently, tserialio does not provide an indication of framing, parity, or overrun errors. TTTTSSSSssssttttaaaattttuuuussss ttttssssWWWWrrrriiiitttteeee((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****ddddaaaattttaaaa,,,, ssssttttaaaammmmpppp____tttt ****ssssttttaaaammmmppppssss,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; Writes (enqueues) nbytes (byte,timestamp) pairs to the specified port's queue. The port must be a TS_DIRECTION_TRANSMIT port (see ttttssssSSSSeeeettttDDDDiiiirrrreeeeccccttttiiiioooonnnn(3)). This call schedules each byte data[i] to go out at the UST time given by stamps[i]. The actual transmission time of data[i] is guaranteed to be within the interval from (stamps[i]) to (stamps[i] + 2 milliseconds). If sufficient space is not available in the port's queue to write all nbytes (byte,timestamp) pairs immediately, then ttttssssWWWWrrrriiiitttteeee(3) will block until it has been able to write all nbytes pairs. If ttttssssWWWWrrrriiiitttteeee(3) needs to block, it will call sssseeeelllleeeecccctttt(2). If that select fails for any reason other than EINTR, the call will return with TS_ERROR_SELECT_FAILED. The timestamps you provide to ttttssssWWWWrrrriiiitttteeee(3) must be non-decreasing. Tserialio will transmit every byte you enqueue exactly once; it will transmit a byte late rather than dropping it. Be careful that the (byte,timestamp) pairs you enqueue on the serial port are (at least in the long term) realizable given the baud rate and communications parameters you have chosen, otherwise you will lose the accuracy guarantee described above, and possibly also overflow your queue. iiiinnnntttt ttttssssGGGGeeeettttFFFFDDDD((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; TTTTSSSSssssttttaaaattttuuuussss ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))));;;; iiiinnnntttt ttttssssGGGGeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss((((TTTTSSSSppppoooorrrrtttt ppppoooorrrrtttt))));;;; ttttssssGGGGeeeettttFFFFDDDD(3) returns a file descriptor which you can pass to sssseeeelllleeeecccctttt(2) or ppppoooollllllll(2) if you want to block until data becomes available in an input port, or space becomes available in an output port. PPPPaaaaggggeeee 7777 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) Before calling sssseeeelllleeeecccctttt(2) or ppppoooollllllll(2), you must first call ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss(3) to specify when you want to unblock: INPUT PORTS: will unblock from select() or poll() when tsGetFilledBytes() >= tsGetFillPointBytes() OUTPUT PORTS: will unblock from select() or poll() when tsGetFilledBytes() < tsGetFillPointBytes() The calls ttttssssWWWWrrrriiiitttteeee(3) and ttttssssRRRReeeeaaaadddd(3) may change the fillpoint, so you should make sure to call ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss(3) before each invocation of sssseeeelllleeeecccctttt(2) or ppppoooollllllll(2). When using sssseeeelllleeeecccctttt(2), an input port's file descriptor is used in a read fdset and an output port's file descriptor is used in a write fdset. When using ppppoooollllllll(2), an input port's file descriptor is used with the POLLIN event flag and an output port's file descriptor is used with a POLLOUT event flag. AL Note: the definition of output fillpoint differs from that in the SGI Audio Library (see AAAALLLLiiiinnnnttttrrrroooo(3dm)). The AL file descriptor unblocks when there are more than "fillpoint" spaces in the queue. This inconsistency was necessary to facilitate a future feature of this library: the ability to choose fillpoints in units of time rather than data. ttttssssSSSSeeeettttFFFFiiiillllllllPPPPooooiiiinnnnttttBBBByyyytttteeeessss(3) will fail with TS_ERROR_BAD_LIBRARY_CALL if _n_b_y_t_e_s is less than zero or greater than the port's queue size. TTTTHHHHRRRREEEEAAAADDDD SSSSAAAAFFFFEEEETTTTYYYY Applications can make multiple, simultaneous, uncoordinated TS calls on different TSports from different threads and the library will operate fine. Each TSport completely encapsulates the state needed to do operations on that TSport (except for error handling, which is explained next). Applications cannot make multiple, simultaneous, uncoordinated TS calls from different threads to set or access the library's global state-- namely, the error handler function described below. If two threads simultaneously try to set the global error handler (even the same error handler), the behavior is undefined. Furthermore, if the application writes an error handler, then makes multiple, simultaneous, uncoordinated TS calls on different TSports from different threads, and both TS calls issue an error simultaneously, then two instances of the application's error handler will be called in a simultaneous, uncoordinated manner in two threads. Applications may need semaphore protection in their error handler if this is possible. Each function in this man page documents the possible error return values. Applications cannot make multiple, simultaneous, uncoordinated TS calls on the same TSport from different threads, even if the order of execution PPPPaaaaggggeeee 8888 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) of those calls does not matter to the application. Doing so will very likely cause a core dump, or at least corruption of the TSport. An application which accesses a given TSport from multiple threads should use a semaphore package such as POSIX semaphores (man sssseeeemmmm____iiiinnnniiiitttt(3C)). EEEERRRRRRRROOOORRRR HHHHAAAANNNNDDDDLLLLIIIINNNNGGGG TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc ttttssssSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc nnnneeeewwwwffffuuuunnnncccc,,,, iiiinnnntttt iiiinnnncccclllluuuuddddeeeeffffuuuunnnnccccnnnnaaaammmmeeee))));;;; TTTTSSSSeeeerrrrrrrrffffuuuunnnncccc ttttssssGGGGeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((iiiinnnntttt ****iiiinnnncccclllluuuuddddeeeeffffuuuunnnnccccnnnnaaaammmmeeee____rrrreeeetttt))));;;; Functions that can err return a TSstatus. TS_SUCCESS means success. On failure, functions return a TS_ERROR_ token as seen in <tserialio.h>, and also set oooosssseeeerrrrrrrroooorrrr(3C) to the value of that token. Errors are also reported as they occur by the execution of a process- global, non-thread-safe error handler callback which you can set. The string passed to the error handler contains detailed error information which is useful for debugging. The default error handler prints an error to stderr. When defining an error handler, you can specify using _i_n_c_l_u_d_e_f_u_n_c_n_a_m_e whether or not to include the TS function name that is erring in the string. Most applications will want to turn off the error handler in non-debug compiles using something like this: #ifdef NDEBUG tsSetErrorHandler(NULL, FALSE); #endif ttttssssSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(3) sets a new error handler and returns the previous handler. ttttssssGGGGeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(3) returns the current error handler and _i_n_c_l_u_d_e_f_u_n_c_n_a_m_e status. _i_n_c_l_u_d_e_f_u_n_c_n_a_m_e__r_e_t can be NULL. Programmatic errors, where you pass an out-of-range, nonsensical, or otherwise illegal value to an TS library call, all return TS_ERROR_BAD_LIBRARY_CALL. PPPPEEEERRRRFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE TTTTIIIIPPPPSSSS Tserialio is built on a mechanism which is extremely lightweight compared to the standard ////ddddeeeevvvv////ttttttttyyyyddddn serial interface. The mechanism is similar to the lightweight mapped ringbuffers offered by the Audio Serial Option (see aaaassssoooosssseeeerrrrnnnnssss(7)). These facts are true of the current implementation and are likely (not guaranteed) to remain true: o ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss(3) performs no system calls and is extremely efficient. PPPPaaaaggggeeee 9999 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) o A ttttssssRRRReeeeaaaadddd(3) which can be satisfied by data currently in the port's queue is little more than a bcopy and requires no system calls. o A ttttssssWWWWrrrriiiitttteeee(3) for which there is room in the port's queue is similarly efficient. Therefore, an application which periodically polls ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss(3) can perform all of its serial i/o without any system calls. This may be desirable for applications in which a convenient periodic opportunity for polling the serial device is available without spinning on the CPU. For example, this may be the case with a video deck control application. AAAACCCCCCCCUUUURRRRAAAACCCCYYYY AAAANNNNDDDD LLLLAAAATTTTEEEENNNNCCCCYYYY Tserialio offers guarantees about the accuracy of its input byte timestamping and its output byte scheduling. These guarantees are described along with ttttssssWWWWrrrriiiitttteeee(3) and ttttssssRRRReeeeaaaadddd(3) above. Tserialio offers no guarantees about the latencies your application sees. It has no interactions whatsoever with the IRIX scheduler. It is a service which pairs together bytes of data and UST times in such a way that your application can manipulate the pair atomically. 1. for input ports, tserialio offers no guarantees about the maximum time between when a byte arrives at the port and when ttttssssRRRReeeeaaaadddd(3) unblocks. 2. for input and output ports, tserialio offers no guarantees about the maximum time between when a byte arrives at the port or is transmitted out the port and when ttttssssGGGGeeeettttFFFFiiiilllllllleeeeddddBBBByyyytttteeeessss(3) starts returning a different value to reflect that transfer. 3. for input and output ports, tserialio offers no guarantees about the maximum time between when a port reaches its fillpoint and when a TSport's file descriptor unblocks a sssseeeelllleeeecccctttt(2) or ppppoooollllllll(2). 4. every program that outputs a serial signal has some "operating latency" LLLL, such that for any given byte that needs to go out at time TTTT, the program will choose to enqueue that byte on the TSport at time TTTT-LLLL or later. Generally (see below) the IRIX scheduler does not guarantee that a process will be running at any given time. Therefore, as LLLL decreases, it becomes increasingly likely that your IRIX process will not be running in the interval between TTTT-LLLL and TTTT and thus will not be able to enqueue the byte for timely transmission. Tserialio offers no guarantee that any particular value of LLLL will always be big enough to avoid this situation. 5. when writing a given (byte, timestamp) pair to an output port using ttttssssWWWWrrrriiiitttteeee(3), you must provide tserialio with enough "advance warning" (ie, the difference between the current UST at the time of ttttssssWWWWrrrriiiitttteeee(3) and the UST timestamp in the pair must be large enough) so that tserialio can schedule output of the data with the accuracy described in ttttssssWWWWrrrriiiitttteeee(3). This "advance warning" must be added into your "operating latency" as PPPPaaaaggggeeee 11110000 TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) TTTTSSSSEEEERRRRIIIIAAAALLLLIIIIOOOO((((3333)))) described above. Tserialio offers no guarantee that any particular amount of "advance warning" will always be enough. Here are some useful facts about the current implementation (not guaranteed to be true of all implementations): o The latency described in item 2 is at most 2ms. o The minimum advance warning described in item 5 is 2ms. o it is possible to reliably perform certain tasks, such as playing a MIDI file or controlling a Sony-protocol RS-422 VTR, using the latencies practically available to a non-degrading-priority IRIX process (see sssscccchhhheeeeddddccccttttllll(2)). Note that emulating a Sony-protocol RS-422 VTR is not necessarily possible. Real latency guarantees such as those described in items 1, 3, and 4 are currently available in multiprocessor configurations using the REACT/Pro product. Such guarantees may be available on all SGI workstations in a future IRIX release. For now, tserialio provides the critical functionality for many timely serial applications. SSSSEEEEEEEE AAAALLLLSSSSOOOO dmGetUST(3dm), serial(7), asoserns(7), termios(7), mdIntro(3dm) PPPPaaaaggggeeee 11111111 
